/**
 * @file raftRpcUtil.h
 * @brief Raft RPC 通信工具类定义
 * 
 * 封装了 Raft 节点间的 RPC 通信功能
 * 提供日志追加、快照安装、投票请求等核心 RPC 接口
 * 负责与其他 Raft 节点的网络通信
 */
#ifndef RAFTRPC_H
#define RAFTRPC_H

#include "raftRPC.pb.h"

/**
 * @class RaftRpcUtil
 * @brief Raft RPC 通信工具类
 * 
 * 维护当前节点对其他某一个节点的所有 RPC 发送通信功能
 * 对于一个 Raft 节点来说，对于任意其他的节点都要维护一个 RPC 连接
 * 
 * 主要功能：
 * - 封装 gRPC 客户端调用
 * - 提供 Raft 核心 RPC 接口
 * - 管理与单个远程节点的连接
 * - 处理网络通信异常
 */
class RaftRpcUtil {
 private:
  raftRpcProctoc::raftRpc_Stub *stub_;  ///< gRPC 客户端存根，用于发起远程调用

 public:
  // ========== 主动 RPC 调用接口 ==========
  /**
   * @brief 发送日志追加 RPC 请求
   * @param args 日志追加请求参数
   * @param response 日志追加响应结果
   * @return 是否调用成功
   * 
   * 用于 Leader 向 Follower 发送日志条目或心跳消息
   * 这是 Raft 算法中最重要的 RPC 调用之一
   */
  bool AppendEntries(raftRpcProctoc::AppendEntriesArgs *args, raftRpcProctoc::AppendEntriesReply *response);
  
  /**
   * @brief 发送快照安装 RPC 请求
   * @param args 快照安装请求参数
   * @param response 快照安装响应结果
   * @return 是否调用成功
   * 
   * 用于 Leader 向落后太多的 Follower 发送快照数据
   * 帮助 Follower 快速追上 Leader 的状态
   */
  bool InstallSnapshot(raftRpcProctoc::InstallSnapshotRequest *args, raftRpcProctoc::InstallSnapshotResponse *response);
  
  /**
   * @brief 发送投票请求 RPC
   * @param args 投票请求参数
   * @param response 投票响应结果
   * @return 是否调用成功
   * 
   * 用于候选者向其他节点请求投票
   * 是 Raft 领导者选举的核心机制
   */
  bool RequestVote(raftRpcProctoc::RequestVoteArgs *args, raftRpcProctoc::RequestVoteReply *response);
  
  // ========== 构造和析构函数 ==========
  /**
   * @brief 构造函数
   * @param ip 远端节点 IP 地址
   * @param port 远端节点端口号
   * 
   * 初始化与指定远程节点的 RPC 连接
   * 创建 gRPC 客户端存根用于后续通信
   */
  RaftRpcUtil(std::string ip, short port);
  
  /**
   * @brief 析构函数
   * 
   * 清理 RPC 连接资源
   * 释放 gRPC 客户端存根
   */
  ~RaftRpcUtil();
};

#endif  // RAFTRPC_H
